home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / tde.zip / TDE.MAN < prev    next >
Text File  |  1992-07-14  |  10KB  |  228 lines
  1.  
  2. FILENAME: TDE.MAN
  3. *****************
  4.                        Class TDataEntry v1.0 - 07/14/92
  5.                        --------------------------------
  6.  
  7.  ----------------------------------------------------------------------------
  8.  Author: Jeff Penrose * JDP Custom Software * (818) 344-7303 * CIS 71043,3727
  9.  ----------------------------------------------------------------------------
  10.  
  11.  A data entry class for Borland's Turbo Vision, derived from TInputLine.
  12.  
  13. Copyright Notice
  14. ================
  15.   As this material is ultimately derived from Borland source files, any of
  16.  their copyrights which MAY apply DO apply.
  17.   From the author's standpoint, you may use this material freely and,
  18.  hopefully, post any comments/corrections/enhancements to me at the above-
  19.  noted addresses.  I do ask that you not distribute this material except as
  20.  originally received, including all source/documentation files in their
  21.  original form.
  22.   If you DO modify or enhance any of this code, please send any such changes
  23.  to me for incorporation into a future version.  Any such enhancements will
  24.  be DONATED, without expectation of compensation or incorporation into
  25.  future versions.  Again, if you distribute this code, please do so in its
  26.  original, unmodified form including all source files and documentation.
  27.  
  28. Source files included
  29. =====================
  30.  TDE     .DOC: This documentation.
  31.  TDE     .MAN: How to use TDataEntry in your dialog objects
  32.  TDE     .H  : header file containing class declarations for classes
  33.  TDEFLAGS.H  :   "     "      "       flags and command definitions
  34.  TDE     .CPP: Class TDataEntry
  35.  TDEDATE .CPP: Class TDEDate
  36.  TDEPHONE.CPP: Classes TDEPhone, TDEZipCode, TDEState
  37.  TDENUMS .CPP: Class TDEInteger
  38.  TDECLUST.CPP: Non-TDataEntry classes TDEButton, TDERadioButtons, TDECheckBoxes
  39.  TDEINPLI.CPP: Non-TDataEntry class TDEInputLine
  40.  TDELIB  .PRJ: Project for building library TDELIB.LIB
  41.  TDEDEMO .CPP: Demo program
  42.  TDEDEMO .PRJ: Project for building TDEDEMO.EXE
  43.  
  44. ***************************************************************************
  45.  
  46.   How to use class TDataEntry in your Applications
  47.   ================================================
  48.  
  49.   BUILD THE LIBRARY
  50.   -----------------
  51.    The project file TDELIB.PRJ is included.  It assumes that all the source
  52.   is in the current directory.  Before using, update Options|Directories
  53.   to reflect the appropriate paths.  It builds the library TDELIB.LIB.
  54.    If you like TDataEntry and want to use it in your applications, you
  55.   can build an overlaid version of the library by studying the compiler
  56.   options in Borlands makefile for TV.LIB.  In particular, you've got to
  57.   set the Compile via Assembler, Local Virtual Tables, etc. options.
  58.  
  59.   USE THE LIBRARY
  60.   ---------------
  61.   1)  You'll probably want to put both TDE.H and TDEFLAGS.H in your
  62.      TVISION\INCLUDE directory or whatever directory you keep your .h
  63.      files in and which is listed in your project's directory list.
  64.  
  65.   2)  You need to #include TDE.H in any file which uses TDataEntry objects.
  66.      (TDEFLAGS.H is brought in by TDE.H, so you don't have to #include it.)
  67.      Before #include'ing TDE.H, #define the appropriate Uses_XXXXXX
  68.      for the TDataEntry classes which you'll be using.  Consult TDE.H for
  69.      the Uses_XXXXX definitions to use.  (This method is a blatant rip-off
  70.      of Borland's method, but it simplifies things and works so well!)
  71.  
  72.   3)  Somewhere before calling TApplication.run(), set the static
  73.      TDataEntry members if you want non-default global behavior.
  74.  
  75.   4) Dialog Box Construction:
  76.       When constructing a dialog box, you should set TDataEntry::globaID = 0
  77.      BEFORE inserting any TDataEntry objects.  This will ensure that the
  78.      objects are numbered starting at 1.  You don't need to do this if you
  79.      won't be using the TDataEntry::locateID() function, but it's best to
  80.      since the code hasn't been tested in the case where TDataEntry::globalID
  81.      exceeds MAX_UCHAR (255).  Theoretically, all fields will be assigned
  82.      the number 255 when TDataEntry::globalID hits 255.
  83.  
  84.       Insert TDataEntry objects as you would any other objects, paying
  85.      attention to constructor syntax (you DON'T specify field length when
  86.      you specify a format).  The default for fieldName is NULL, so if you
  87.      leave it off no field name will be assigned.
  88.  
  89.       If you want to modify the field's localMode member, you must get a
  90.      pointer to the object, then access localMode through the pointer:
  91.      .......
  92.      TView  *v;  (real generic so you can use it with anything you insert)
  93.  
  94.      TDataEntry::globalID = 0;
  95.  
  96.      insert((v = new TDEDate( 2, 4, "~~/~~/~~", "myField")));
  97.      //* The TDEDate object uses TDEData::defCentury for the century and uses
  98.      //*  MM/DD/YY format by default.  The field has been assigned the name
  99.      //*  'myField'
  100.  
  101.      ((TDataEntry *)v)->localMode |= (tdlAutoExit | tdlRequired);
  102.      //* The object will exit automatically when the last digit is entered
  103.      //*  and validation will require that this field be non-blank.
  104.      ......
  105.  
  106.       Be sure to use the TDEButton, TDEInputLine, TDERadioButtons, and
  107.      TDECheckBoxes objects instead of the standard ones.  These objects
  108.      behave in a manner consistent with TDataEntry object behavior and, in
  109.      addition, respond to some of TDataEntry's query functions.
  110.  
  111.   5)  THAT'S IT!  THE REST IS UP TO YOU.  You'll probably want to use some
  112.      of TDataEntry's query functions prior to allowing a dialog to close.
  113.      Your dialog's valid() function should call TDataEntry::queryChanged()
  114.      when it gets cmClose/cmCancel/cmQuit messages.  Prior to saving data,
  115.      you'll want to call TDataEntry::queryValid() to verify data integrity
  116.      before committing it to disk.  ( REMEMBER: inter-field movement via
  117.      mouse does NOT perform field validation, so bad data can slip through
  118.      during data entry )
  119.  
  120.   6) ONE MORE THING: Don't forget to add TDELIB.LIB to your project!
  121.  
  122.   USING THistory with TDataEntry objects
  123.   ======================================
  124.    The problem with using THistory with TDataEntry objects is twofold:
  125.      a) If TDataEntry::globalMode's tdgUpDownEnable flag is set, then a
  126.         kbDown event will not be seen by THistory, preventing it from
  127.         responding.
  128.      b) THistory assumes it's attached to a TInputLine object.  When it
  129.         calls selectAll() upon close, it calls TInputLine's selectAll()
  130.         rather than TDataEntry's [selectAll() is not virtual in TInputLine].
  131.         In addition, you may not want the data to be selected anyway, pre-
  132.         ferring that it act according to TDataEntry::globalMode's
  133.         tdgSelectOnFocus flag.
  134.  
  135.    The solution is as follows:  You MUST derive a THistory object that's
  136.    TDataEntry-friendly.  In addition, if you have the TDataEntry::globalMode
  137.    tdgUpDownEnable flag set, you must derive a new TDataEntry object.  It's
  138.    best to do both so that everything works later if your project's design
  139.    changes. Fortunately, both of these solutions are simple:
  140.  
  141.    A) DERIVE A NEW TDataEntry OBJECT
  142.    ---------------------------------
  143.  
  144.    class TNumLookup : public TDENumeric  //* or some other TDataEntry object
  145.    {
  146.      public:
  147.        //* I've only defined a constructor using TDE's CONSTRUCTOR 2
  148.        //* You can define either one or both as needed
  149.        TNumLookup(int x, int y, int w, const char *fName = NULL) :
  150.          TDENumeric( x, y, w, fName )  {};
  151.        virtual void handleEvent( TEvent& event );
  152.    };
  153.  
  154.    void TNumLookup::handleEvent( TEvent& event )
  155.    {
  156.       TView::handleEvent(event);
  157.       if ( event.what == evKeyDown && event.keyDown.keyCode == kbDown )
  158.       return;  //** let TTarHistory grab this one
  159.  
  160.       TDENumeric::handleEvent( event );
  161.    }
  162.  
  163.    B) DERIVE A NEW THistory OBJECT
  164.    -------------------------------
  165.  
  166.    class TDEHistory : public THistory
  167.    {
  168.      public:
  169.        TDEHistory(const TRect& bounds, TInputLine *aLink, ushort aHistoryId) :
  170.          THistory( bounds, aLink, aHistoryId ) {};
  171.  
  172.        virtual void  handleEvent(TEvent& event);
  173.  
  174.      private:  //* necessary because THistory's icon is private
  175.       static  const char * near icon;
  176.    };
  177.  
  178.    const char * near TTarHistory::icon = "\xDE~\x19~\xDD";
  179.  
  180.    void TDEHistory::handleEvent( TEvent& event )
  181.    {
  182.      THistoryWindow *historyWindow;
  183.      TRect  r, p;
  184.      ushort c;
  185.  
  186.      TView::handleEvent( event );
  187.      if( event.what == evMouseDown ||
  188.          (event.what == evKeyDown &&
  189.           ctrlToArrow( event.keyDown.keyCode ) == kbDown &&
  190.           (link->state & sfFocused) != 0)
  191.        )
  192.      {
  193.        link->select();
  194.        historyAdd( historyId, link->data );
  195.        r = link->getBounds();
  196.        r.a.x--; r.b.x++; r.b.y += 7; r.a.y--;
  197.        p = owner->getExtent();
  198.        r.intersect( p );
  199.        r.b.y--;
  200.        historyWindow = initHistoryWindow( r );
  201.        if( historyWindow != 0 )
  202.        {
  203.          c = owner->execView( historyWindow );
  204.          if( c == cmOK )
  205.          {
  206.            char rslt[256];
  207.            historyWindow->getSelection( rslt );     //** JDP
  208.            ((TDataEntry *)link)->setData(rslt);
  209.            // strncpy( link->data, rslt, link->maxLen );
  210.            if ( (TDataEntry::globalMode & tdgSelectOnFocus) != 0 )
  211.              ((TDataEntry *)link)->selectAll( True );
  212.            ((TDataEntry *)link)->drawView();
  213.          }
  214.          destroy( historyWindow );
  215.        }
  216.        clearEvent( event );
  217.      }
  218.      else
  219.        THistory::handleEvent(event);
  220.    }
  221.  
  222.   //******************** TDE.MAN ends *******************************//
  223.  
  224.  
  225.  
  226.  
  227.  
  228.